Games of Daze/Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso/x2ftp/msdos/libs/otm3d095/3dtools.ref

Text File | 1994-12-12 | 19.2 KB | 728 lines

        3dtools v0.95 function reference

        Copyright (C) 1994 Zach Mortensen [Voltaire/OTM]


        This document describes the classes used in 3dtools, along
        with their member data and functions.  This is NOT a tutorial
        3d math, nor is it a tutorial in object oriented programming.




int dotProduct(point3d *p1, point3d *p2);

        Returns the dot product of two vectors, p1 and p2.  This function is
        not a member of any class.




class point3d

        This class is used to store all the data pertinent to 3d points
        (vectors).  Objects of type point3d are the basis for all other
        objects used by 3dtools, so it is vital that the workings of this
        object be understood.


MEMBER DATA

public:

    long x3d, y3d, z3d;

        x3d, y3d, and z3d are the GLOBAL coordinates of this point.  GLOBAL
        coordinates are defined in terms of THE origin <0,0,0>.  After
        every operation on the point, a new set of global coordinates is
        calculated which represent the new position of the point with
        respect to THE (<0,0,0>) origin.


    long localX, localY, localZ;

        localX, localY, and localZ are the LOCAL coordinates of this point.
        LOCAL coordinates are defined in terms of another point, usually
        the center of an OBJECT which contains many points.  The LOCAL
        coordinates stored in these variables are not modified by any
        operation.  This is useful if you want to implement a different
        type of rotation which employs the use of unit vectors.  I
        implemented unit vector rotation, but it turned out to be slightly
        slower than matrix rotation so I scrapped it.  The original local
        coordinates still come in handy from time to time, so I kept them.


    long rotoX, rotoY, rotoZ;

        rotoX, rotoY, and rotoZ are the ROTATED LOCAL coordinates of this
        point.  They are redefined with every rotational operation.


    long oX, oY, oZ;

        oX, oY, and oZ are the coordinates of the LOCAL ORIGIN which the
        local coordinates (localX, localY, localZ) are defined in terms of.
        oX, oY, and oZ are defined in terms of THE (<0,0,0>) origin.  There
        are a number of member functions which are designed to perform
        various operations on the origin.


    long x2d, y2d;

        x2d and y2d are the SCREEN coordinates of this point.  A perspective
        transformation is applied to the GLOBAL coordinates to obtain the
        SCREEN coordinates.


    long nX, nY, nZ, nCount;

        nX, nY, and nZ are the coordinates of a NORMAL VECTOR which is the
        average of the normal vectors of all planes which share this point.
        These variables are used to find the average of the normals only,
        they do NOT contain updated normal coordinates following any
        operations done on this point.  nCount contains the number of
        normals currently summed in these variables.


    void *normal;

        normal is a pointer to another point3d object which contains the
        data for a vector which is the average of the normals of all planes
        that share this point.  It is of type void in order to avoid
        recursive definitions, in which every normal would have an actual
        class point3d normal which would have its own normal...and we would
        have no more memory!  The (void *) is typecast to (point3d *) when
        the data is needed.  The information contained here is used by
        Gouraud shading routines to determine the average intensity of
        light falling on this point.

private:

    long i, j, k;

        These are temporary integers used in many different calculations,
        including non matrix rotation and vector normalization.  They are
        private because the values contained in them are not very important
        to anyone besides this point.


    int xDeg, yDeg, zDeg;

        xDeg, yDeg, and zDeg store the total number of degrees this object
        has been rotated about each respective axis.  This quantity is
        positive and % 360, so values are always in the range 0-359.




        MEMBER FUNCTIONS


    void save(FILE *fp);
    void load(FILE *fp);

        THESE DO NOT WORK, SO DO NOT USE THEM!  They were left over from
        an old version of 3dtools, and they do not save all the necessary
        data to reconstruct the newest objects.  If you feel the urge, you
        may rewrite them to suit your needs.


    void setTo(long x, long y, long z);

        This function sets the point to GLOBAL AND LOCAL coordinates <x,y,z>.
        it also redifines the point's origin to be THE (<0,0,0>) origin.


    void xform2d();

        Applies a perspective transformation to the point, calculating new
        screen coordinates <x2d, y2d>.  Because some points are not displayed
        (some represent normal vectors), this function is NOT automatically
        called by the point itself following any operations.


    void display(int color);

        Displays this point at screen coordinates <x2d, y2d> in color (color).


    void setNewOrigin(point3d *p);

        Sets the origin coordinates <oX,oY,oZ> to the <x3d,y3d,z3d>
        coordinates of point p.  The local coordinates of this point remain
        the same, and the global coordinates are altered to represent the
        local coordinates in terms of the new origin.


    void globalXform2origin(point3d *p);

        Same as setNewOrigin, with the exception that it performs a global
        transformation on the point's <rotoX,rotoY,rotoZ> coordinates to
        obtain a new set of global coordinates defined in terms of the
        new origin's global coordinates.


    void copyOrigin(point3d *p);

        Same as globalXform2origin, with the exception that the global
        transformation is applied using the ORIGIN (<oX,oY,oZ>) coordinates
        of point p rather than the GLOBAL (<x3d,y3d,z3d>) coordinates.


    void localRotate(int tX, int tY, int tZ);

        Rotates this point about its LOCAL (<oX,oY,oZ>) origin.  Adds
        <tX,tY,tZ> to <xDeg,yDeg,zDeg> and calculates the new
        <rotoX,rotoY,rotoZ> coordinates.


    void localRotate(int *trig);

        This function performs the same task as the other localRotate,
        with the exception that it is used almost exclusively by the obj3d
        class to rotate its member points.  It is much faster than the other
        localRotate function because the trigonometric multipliers which are
        stored in the trig array are constant for all points in a given
        object.  The structure of array trig is as follows

        trig[0] = sin tX
        trig[1] = cos tX
        trig[2] = sin tY
        trig[3] = cos tY
        trig[4] = sin tZ
        trig[5] = cos tZ

        All these quantities must be expressed in 8.8 fixed point.


    void matRotate();

        Fastest type of local rotation, makes use of a rotation matrix set
        up by an instance of class obj3d.  Matrix rotation is slower for
        objects of less than 4 points because of the overhead required to
        set up the matrix.


    void globalRotate(int *trig);

        Rotates the point about THE (<0,0,0>) origin.  The trig array in
        this case is also passed from an instance of class obj3d, however
        the multipliers in the array are constant for every point in the
        3d world.  The trig array has the same format as the array used
        by localRotate(int *trig).


    void translate(long dX, long dY, long dZ);

        Translates (moves) this point.  New coordinates are <x3d + dX,
        y3d + dY, z3d + dZ>.


    void globalXform();

        Performs a global transformation on this point, adding
        <rotoX,rotoY,rotoZ> to <oX,oY,oZ> to obtain <x3d,y3d,z3d>.


    void zeroNormal();

        Clears the values stored in <nX,nY,nZ> to prepare for calculating
        a new normal value.


    void addNormal(int dX, int dY, int dZ);

        Adds <dX,dY,dZ> to <nX,nY,nZ> and increments nCount.


    void avgNormal();

        Divides <nX,nY,nZ> by nCount to obtain an average normal for this
        point, and adjusts (normalizes) the resultant vector to have a
        magnitude of 256.






class line3d


        The line3d class was an integral part of 3dtools at one time, but
        it is fairly useless now considering the fact that I began writing
        my own video library and have absolutely no desire to write a line
        drawing routine.  Its primary function is to display lines for
        wireframe models, however, it also contains functions dealing with
        a parametric representation of itself.


        MEMBER DATA

private:

    point3d *point1, *point2;

        The endpoints of the line.


    int color;

        The color used in displaying the line.


    long i, j, k;

        Temporary values used in parametric calculations.




        MEMBER FUNCTIONS

public:

    void draw();

        Draws the line using its designated color.


    void calcVectors();

        Calculate vectors used in parametric calculations.


    long xOfT(double t);
    long yOfT(double t);
    long zOfT(double t);

        Return the value of <x,y,z> given a parameter t.


    double tOfX(long x);
    double tOfY(long y);
    double tOfZ(long z);

        Return the value of a parameter t at a given <x,y,z>.


    void localRotate(double tX, double tY, double tZ);

        Calls localRotate for the endpoints of the line, results are
        unpredictable if p1 and p2 are defined in terms of different
        origins.




        Constants for class polygon

#define sNone       0
#define sFlat       1
#define sGouraud    2

        Used to designate the type of shading to be used when drawing this
        polygon.


#define fBoth       0
#define fInside     1
#define fOutside    2

        Used by plane elimination routines to define which direction the
        plane is facing when its points are listed in a clockwise manner
        (3dStudio lists its points clockwise, but the mathematically
        correct order is counterclockwise).



class polygon


        MEMBER DATA

public:

    point3d *p1, *p2, *p3, *normal;

        p1, p2, and p3 define the vertices of the polygon.  normal defines
        a vector perpendicular to the plane.


    int color;

        The color of this plane.  In flat or gouraud shaded planes, color
        MUST be the first in a range of 16 palette colors ranging from
        darkest to lightest in order for the plane to be shaded correctly!


    int facing, shading;

        The direction this plane is facing, and the type of shading to be
        used.

private:

    line3d **line;

        Array of line3d objects which define the lines used to draw plane as
        a wireframe.


    int count, dot, dot1, dot2, dot3;

        Temporary variables. count is a counter which is reused.  The dot
        variables are used to hold the values of the dot products of
        each normal while color intensities are being calculated.


        MEMBER FUNCTIONS


    void setTo(point3d *v1, point3d *v2, point3d *v3);

        Defines the plane in terms of {v1,v2,v3}.


    long avgZ();

        Returns the average z value of the plane, used in sorting routines.
        The divide in this routine may be eliminated with no loss in sorting
        accuracy.


    void setColor(int c);

        Set this plane to color c, or a range of 16 colors beginning at c.


    void wireFrame();

        Displays the polygon as a wireframe, not currently implemented due
        to laziness on my part.  I don't want to waste time coding a line
        drawing routine, and I never use wireframes, so why bother?


    void paintSolid();

        Flat fills the polygon, no z-buffering.


    void gShade();

        Gouraud shades the polygon, calls gzpoly3 to use z-buffered
        drawing.  To eliminate z-buffered drawing, call gpoly3 instead.


    void setNewOrigin(point3d *p);

        Calls setNewOrigin for all vertices and the normal.


    void localRotate(int *trig);

        Calls localRotate for all vertices and the normal, not advisable in
        instances of class obj3d due to the fact that multiple planes share
        a single point.


    void globalRotate(int *trig);

        Calls globalRotate for vertices and the normal.  Same word of
        caution when dealing with class obj3d.


    void setGNormals();

        Adds the calls addNormal(normal) for each of the vertices of this
        plane.


    void setShading(int shade);

        Set the type of shading to be used.


    void setFacing(int face);

        Set the direction in which the plane is facing.


    void display();

        Display the plane using the information contained in (shading) and
        (facing).


    void zbFlat();

        Flat fills the polygon using z-buffered drawing.




class obj3d


        MEMBER DATA

private:

    point3d *origin;

        This point contains information about the local origin of the
        object.


    line3d *xAxis, *yAxis, *zAxis;

        These were originally to define unit vectors of the object, they
        have no use now,


    int *trig;

        Contains rotation multipliers which are constant for the entire
        object


public:

    point3d  **point;

        List of points which make up the object.


    point3d  **normal;

        List of normals to this object's points and planes.  Points in this
        list are rotated, translated, etc. but are not perspective
        transformed to obtain screen coordinates since they are never
        displayed.


    polygon  **poly;

        List of polygons which make up the object.


    int numPoints, numNormals, numPolys;

        Number of points, normals, and polygons present in the respective
        lists.


    int xDeg, yDeg, zDeg;

        Number of degrees the object has been rotated about each respective
        axis, always in the range 0-359.


    int count;

        Counter variable.




        MEMBER FUNCTIONS



    void save(FILE *fp);
    void load(FILE *fp);

        THESE DON'T WORK, they were designed for a previous version and no
        longer store enough information.  They can be easily modified .

    void addLocalPoint(long x, long y, long z);

        Add a point, redefining its global coordinates in terms of the
        object's origin.  The point's local coordinates remain the same


    void addLocalPoint(point3d *p);

        Same as the above.


    void addGlobalPoint(long x, long y, long z);

        Add a point, redefining its local coordinates in terms of the
        object's origin.  The points global coordinates remain the same.


    void addGlobalPoint(point3d *p);

        Same as the above.


    void addLocalPoly(polygon *pg);

        Add a polygon and adds its normal to the normal list.  Does NOT add
        the vertices to the point list!


    void addLocalPoly(int p1, int p2, int p3, int c);

        Creates a new polygon defined in terms of existing points in the
        point list and adds it to the object.


    void addGlobalPoly(polygon *pg);

        Adds a polygon whose vertices are defined in terms of THE (<0,0,0>)
        origin.


    int getPointNum(long x, long y, long z);

        Returns the index in the point list of a point with the given LOCAL
        coordinates.  If a point is not found, one is created and added
        to the list.


    int getPointNum(point3d *p);

        Returns the index in the point list of a point, returns (-1) if
        is not found.


    void localRotate(int tX, int tY, int tZ);

        Rotate the object around its origin.  Rotates points and normals,
        and perspective transforms points only.


    void globalRotate(int *trig);

        Rotate the object about THE (<0,0,0>) origin.  Same methodology
        as above.


    void translate(int dX, int dY, int dZ);

        Adds <dX,dY,dZ> to the origin, each point and each normal.


    void sortPlanes();

        Uses a linear sort to depth sort the planes from back to front.


    void paintDots();

        Display each point in the point list.


    void wireFrame();

        Display each polygon as a wireframe.


    void paintSolid();

        Flat fill each polygon by calling the paintSolid member of each
        polygon in the list.


    void gShade();

        Gouraud shade each polygon by calling the gShade member of each
        polygon in the list.


    void setLocation(long x, long y, long z);

        Set the location of this object in terms of THE (<0,0,0>) origin.


    void setGNormals();

        Set up normals to points, necessary for gouraud shading an object.
        However, use only if you are gouraud shading, this function doubles
        the number of normals in the normal list!


    void display();

        Display each polygon by calling the display member of each polygon
        in the list.


    void zbFlat();

        Display each polygon by calling the zbFlat member of each polygon
        in the list.


    void addNormal(long x, long y, long z);

        Create a normal with the given LOCAL coordinates and add it to the
        normal list.


    void addNormal(point3d *p);

        Add a normal to the normal list.


    void matRotate(int tX, int tY, int tZ);

        Set up a rotation matrix and call the matRotate member of each
        point and normal, then perspective transforms all points in the
        point list.  This is by FAR the fastest way to rotate.



        W       A       R       N       I       N       G


        The world3d and viewPoint classes are not fully implemented!

class world3d

        Totally unimplemented...nothing useful as of yet


extern world3d world;

        This is THE WORLD, all instances of class obj3d will be listed in
        world, and consequently the world may be rotated, translated, etc.


class viewPoint


        MEMBER DATA

public:

    point3d *location, *light, *view;

        location is the location of the eye, which is always <0,0,0>.
        light is a vector of magnitude 1 which defines the direction of
        the light in the world.  A magnitude of 1 combined with an integer
        coordinate system means that the only valid values for light are
        <0,0,1> <0,1,0> <1,0,0> <0,0,-1> <0,-1,0> and <-1,0,0>.  The default
        is <0,0,1>, in which case the light is coming from a point an
        infinite distance behind the eye and is travelling into the plane of
        the screen.  view defines the current viewing vector, which is always
        <0,0,1>, the eye is always looking directly into the screen.


        MEMBER FUNCTIONS

        none!  None are currently implemented, that is...


extern viewPoint camera;


        THE eye, YOU, the viewer...